<!DOCTYPE html>
<html lang="en">
<head>
		<title>SKiDL &mdash; A Taste of Hierarchy</title>
		<meta charset="utf-8" />
		<link rel="profile" href="http://gmpg.org/xfn/11" />
		<link rel="stylesheet" type="text/css" href="/skidl/theme/css/style.css" />
		<link rel='stylesheet' id='oswald-css'  href='http://fonts.googleapis.com/css?family=Oswald&#038;ver=3.3.2' type='text/css' media='all' />
		<link rel="preconnect" href="https://fonts.googleapis.com">
		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
		<link href="https://fonts.googleapis.com/css2?family=Oswald&family=Roboto+Condensed&display=swap" rel="stylesheet">
		<!-- <style type="text/css">
			body.custom-background { background-color: #f5f5f5; }
		</style> -->
		<link rel="alternate" type="application/atom+xml"
			title="SKiDL — Flux Atom"
			href="/skidl/" />
		<!--[if lte IE 8]><script src="/skidl/theme/js/html5shiv.js"></script><![endif]-->
</head>

<body class="home blog custom-background " >
	<div id="container">
		<div id="header">
				<h1 id="site-title"><a href="/skidl"><img src="/skidl/images/banner.png" width="100%"></a></h1>
				<!-- <h1 id="site-title"><a href="/skidl">SKiDL</a></h1> -->
		</div><!-- /#banner -->

		<div id="menu">
			<div class="menu-navigation-container">
				<ul id="menu-navigation" class="menu">
						<li class="menu-item menu-item-type-post_type menu-item-object-page"><a href="https://github.com/devbisme/skidl">Github</a></li>
						<li class="menu-item menu-item-type-post_type menu-item-object-page"><a href="https://github.com/devbisme/skidl/discussions">Forum</a></li>
						<li class="menu-item menu-item-type-post_type menu-item-object-page"><a href="/skidl/category/posts.html">Blog</a></li>
						<li class="menu-item menu-item-type-post_type menu-item-object-page"><a href="/skidl/api/html/index.html">API</a></li>
						<li class="menu-item menu-item-type-post_type menu-item-object-page"><a href="/skidl/">Home</a></li>

				</ul>
			</div> <!--/#menu-navigation-container-->
		</div><!-- /#menu -->

		<div class="page-title">
		</div>

		<div id="contents">

<div class="post type-post status-publish format-standard hentry category-general" id="post">
	<div class="entry-meta">
		<span class="date"><a href="/skidl/a-taste-of-hierarchy-2017-02-03.html">Fri 03 February 2017</a></span>
		/
		<span class="byline"><a href="/skidl/author/dave-vandenbout.html">Dave Vandenbout</a></span>
	</div> <!-- /#entry-meta -->
	<div class="main">
		<h2 class="entry-title">
			<a href="/skidl/a-taste-of-hierarchy-2017-02-03.html" title="Permalink to A Taste of Hierarchy" rel="bookmark">A Taste of Hierarchy</a>
		</h2>
		<div class="entry-content">
			<p>In my previous blog posts, the SKiDL circuit descriptions were <em>flat</em>.
In this post, I'll show a bit of how to describe a circuit <em>hierarchically</em>.</p>
<p>Hierarchy is typically used when there is some subcircuit that needs to be
replicated several times or which can serve as a module in several different designs.
In the USB-to-JTAG interface board, the crystal with its two trimming capacitors
is a good candidate for encapsulation in a subcircuit because this combination
of components appears in many circuits.
Here's what a SKiDL subcircuit for the crystal circuit looks like:</p>
<div class="highlight"><pre><span></span><code><span class="nd">@SubCircuit</span>
<span class="k">def</span> <span class="nf">osc</span><span class="p">(</span><span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Attach a crystal and two caps to the osc1 and osc2 nets.&#39;&#39;&#39;</span>
    <span class="n">xtal</span> <span class="o">=</span> <span class="n">Part</span><span class="p">(</span><span class="n">xess_lib</span><span class="p">,</span> <span class="s1">&#39;XTAL4&#39;</span><span class="p">,</span> <span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;XESS:32x25-4&#39;</span><span class="p">)</span> <span class="c1"># Instantiate the crystal from the library.</span>
    <span class="n">xtal</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span> <span class="o">+=</span> <span class="n">gnd</span>                   <span class="c1"># Connect the crystal ground pins.</span>
    <span class="n">xtal</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>            <span class="c1"># Connect the crystal pins to the oscillator nets.</span>
    <span class="n">trim_cap</span> <span class="o">=</span> <span class="n">cap</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s1">&#39;10pf&#39;</span><span class="p">)</span>     <span class="c1"># Instantiate a pair of trimmer caps.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">gnd</span>      <span class="c1"># Connect the trimmer caps to the crystal.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span>
</code></pre></div>

<p>The <code>@SubCircuit</code> decorator handles some housekeeping that's necessary to
integrate the encapsulated circuit into the larger whole.
That's followed by a Python function containing SKiDL code for the subcircuit.
(Look back at <a href="/blog/building-a-usb-to-jtag-interface-using-skidl">this post</a>
for a description of what this code does.)</p>
<p>Once the subcircuit is defined, all you need to do is call it somewhere within the
main SKiDL code:</p>
<div class="highlight"><pre><span></span><code><span class="n">osc</span><span class="p">(</span> <span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC1&#39;</span><span class="p">],</span> <span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC2&#39;</span><span class="p">],</span> <span class="n">gnd</span> <span class="p">)</span>
</code></pre></div>

<p>The function call will pass the oscillator pins of the PIC32 microcontroller to the
subcircuit so they can be attached to the crystal and capacitors (along with the
ground net, <code>gnd</code>).</p>
<p>Now, there are several problems that make this subcircuit less than ideal:</p>
<ol>
<li>It depends upon the <code>xess_lib</code> global variable to find the library with the crystal.</li>
<li>It uses a fixed crystal type from that library: <code>XTAL4</code>.</li>
<li>It references the global <code>cap</code> template to instantiate the trimming capacitors.</li>
</ol>
<p>In order to make the subcircuit more general, we can pass the crystal and capacitor
parts as parameters to the function:</p>
<div class="highlight"><pre><span></span><code><span class="nd">@SubCircuit</span>
<span class="k">def</span> <span class="nf">osc</span><span class="p">(</span><span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span><span class="p">,</span> <span class="n">crystal</span><span class="p">,</span> <span class="n">cap</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Attach a crystal and two caps to the osc1 and osc2 nets.&#39;&#39;&#39;</span>
    <span class="n">xtal</span> <span class="o">=</span> <span class="n">crystal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>                  <span class="c1"># Instantiate the crystal from the template.</span>
    <span class="n">xtal</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span> <span class="o">+=</span> <span class="n">gnd</span>                  <span class="c1"># Connect the crystal ground pins.</span>
    <span class="n">xtal</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>           <span class="c1"># Connect the crystal pins to the oscillator nets.</span>
    <span class="n">trim_cap</span> <span class="o">=</span> <span class="n">cap</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s1">&#39;10pf&#39;</span><span class="p">)</span>    <span class="c1"># Instantiate a pair of trimmer caps.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">gnd</span>     <span class="c1"># Connect the trimmer caps to the crystal.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span>
</code></pre></div>

<p>But that means you have to create the template for the crystal before calling the
<code>osc</code> function:</p>
<div class="highlight"><pre><span></span><code><span class="n">crystal</span> <span class="o">=</span> <span class="n">Part</span><span class="p">(</span><span class="n">xess_lib</span><span class="p">,</span> <span class="s1">&#39;XTAL4&#39;</span><span class="p">,</span> <span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;XESS:32x25-4&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span>
<span class="n">osc</span><span class="p">(</span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC1&#39;</span><span class="p">],</span> <span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC2&#39;</span><span class="p">],</span> <span class="n">gnd</span><span class="p">,</span> <span class="n">crystal</span><span class="p">,</span> <span class="n">cap</span><span class="p">)</span>
</code></pre></div>

<p>This works fine as long as you're using a crystal in a four-pin package.
But many crystals only have two terminals.
You can handle that in the subcircuit function as follows:</p>
<div class="highlight"><pre><span></span><code><span class="nd">@SubCircuit</span>
<span class="k">def</span> <span class="nf">osc</span><span class="p">(</span><span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span><span class="p">,</span> <span class="n">crystal</span><span class="p">,</span> <span class="n">cap</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Attach a crystal and two caps to the osc1 and osc2 nets.&#39;&#39;&#39;</span>
    <span class="n">xtal</span> <span class="o">=</span> <span class="n">crystal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>                  <span class="c1"># Instantiate the crystal from the template.</span>
    <span class="n">num_xtal_pins</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">xtal</span><span class="p">[</span><span class="s1">&#39;.*&#39;</span><span class="p">])</span>    <span class="c1"># Get the number of pins on the crystal.</span>
    <span class="k">if</span> <span class="n">num_xtal_pins</span> <span class="o">==</span> <span class="mi">4</span><span class="p">:</span>             <span class="c1"># This handles a 4-pin crystal...</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span> <span class="o">+=</span> <span class="n">gnd</span>              <span class="c1"># Connect the crystal ground pins.</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>       <span class="c1"># Connect the crystal pins to the oscillator nets.</span>
    <span class="k">else</span><span class="p">:</span>                              <span class="c1"># Otherwise assume it&#39;s a 2-pin crystal...</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>        <span class="c1"># Using a two-pin crystal.</span>
    <span class="n">trim_cap</span> <span class="o">=</span> <span class="n">cap</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s1">&#39;10pf&#39;</span><span class="p">)</span>    <span class="c1"># Instantiate a pair of trimmer caps.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">gnd</span>     <span class="c1"># Connect the trimmer caps to the crystal.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span>
</code></pre></div>

<p>The wildcard regular expression makes <code>xtal['.*']</code> return a list of all of its pins.
Then, the Python <code>len</code> operator gets the length of the list and tells us how many pins the crystal has.
After that, it's just a matter of connecting the right pins depending upon how many there are.
Now if you call the <code>osc</code> function with a two-pin crystal, it will work correctly:</p>
<div class="highlight"><pre><span></span><code><span class="n">crystal</span> <span class="o">=</span> <span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span> <span class="s1">&#39;Crystal&#39;</span><span class="p">,</span> <span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Crystal:Crystal_HC49-U_Vertical&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span>
<span class="n">osc</span><span class="p">(</span><span class="o">*</span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC1, OSC2&#39;</span><span class="p">],</span> <span class="n">gnd</span><span class="p">,</span> <span class="n">crystal</span><span class="p">,</span> <span class="n">cap</span><span class="p">)</span>
</code></pre></div>

<p>Of course, sometimes you might want a simpler way to instantiate the subcircuit
without having to pass components as parameters.
Python default parameters come to the rescue!</p>
<div class="highlight"><pre><span></span><code><span class="nd">@SubCircuit</span>
<span class="k">def</span> <span class="nf">osc</span><span class="p">(</span><span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span><span class="p">,</span> 
        <span class="n">crystal</span> <span class="o">=</span> <span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span> <span class="s1">&#39;Crystal&#39;</span><span class="p">,</span> <span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Crystal:Crystal_HC49-U_Vertical&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">),</span> 
        <span class="n">cap</span> <span class="o">=</span> <span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="s1">&#39;C&#39;</span><span class="p">,</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;10pf&#39;</span><span class="p">,</span> <span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Capacitors_SMD:C_0603&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span> <span class="p">):</span>
<span class="w">    </span><span class="sd">&#39;&#39;&#39;Attach a crystal and two caps to the osc1 and osc2 nets.&#39;&#39;&#39;</span>
    <span class="n">xtal</span> <span class="o">=</span> <span class="n">crystal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>                  <span class="c1"># Instantiate the crystal from the template.</span>
    <span class="n">num_xtal_pins</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">xtal</span><span class="p">[</span><span class="s1">&#39;.*&#39;</span><span class="p">])</span>    <span class="c1"># Get the number of pins on the crystal.</span>
    <span class="k">if</span> <span class="n">num_xtal_pins</span> <span class="o">==</span> <span class="mi">4</span><span class="p">:</span>             <span class="c1"># This handles a 4-pin crystal...</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span> <span class="o">+=</span> <span class="n">gnd</span>              <span class="c1"># Connect the crystal ground pins.</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>       <span class="c1"># Connect the crystal pins to the oscillator nets.</span>
    <span class="k">else</span><span class="p">:</span>                              <span class="c1"># Otherwise assume it&#39;s a 2-pin crystal...</span>
        <span class="n">xtal</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">osc2</span>        <span class="c1"># Using a two-pin crystal.</span>
    <span class="n">trim_cap</span> <span class="o">=</span> <span class="n">cap</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>                  <span class="c1"># Instantiate some trimmer caps.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc1</span><span class="p">,</span> <span class="n">gnd</span>     <span class="c1"># Connect the trimmer caps to the crystal.</span>
    <span class="n">trim_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o">+=</span> <span class="n">osc2</span><span class="p">,</span> <span class="n">gnd</span>
</code></pre></div>

<p>Now you can instantiate the default oscillator circuit with the function call:</p>
<div class="highlight"><pre><span></span><code><span class="n">osc</span><span class="p">(</span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC1&#39;</span><span class="p">],</span> <span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC2&#39;</span><span class="p">],</span> <span class="n">gnd</span><span class="p">)</span>
</code></pre></div>

<p>Finally, here's the <a href="/files/a-taste-of-hierarchy/intfc_brd.py">complete SKiDL program</a> so you can see how it fits together:</p>
<div class="highlight"><pre><span></span><code><span class="kn">from</span><span class="w"> </span><span class="nn">skidl</span><span class="w"> </span><span class="kn">import</span><span class="w"> </span><span class="o">*</span>

<span class="nd">@SubCircuit</span>
<span class="k">def</span><span class="w"> </span><span class="nf">osc</span><span class="p">(</span><span class="n">osc1</span><span class="p">,</span><span class="w"> </span><span class="n">osc2</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span><span class="p">,</span><span class="w"> </span>
<span class="w">        </span><span class="n">crystal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;Crystal&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Crystal:Crystal_HC49-U_Vertical&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">),</span><span class="w"> </span>
<span class="w">        </span><span class="n">cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;C&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;10pf&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Capacitors_SMD:C_0603&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span><span class="w"> </span><span class="p">):</span>
<span class="w">    </span><span class="s1">&#39;&#39;&#39;Attach a crystal and two caps to the osc1 and osc2 nets.&#39;&#39;&#39;</span>
<span class="w">    </span><span class="n">xtal</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">crystal</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="w">                  </span><span class="c1"># Instantiate the crystal from the template.</span>
<span class="w">    </span><span class="n">num_xtal_pins</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">len</span><span class="p">(</span><span class="n">xtal</span><span class="p">[</span><span class="s1">&#39;.*&#39;</span><span class="p">])</span><span class="w">    </span><span class="c1"># Get the number of pins on the crystal.</span>
<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="n">num_xtal_pins</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">4</span><span class="p">:</span><span class="w">             </span><span class="c1"># This handles a 4-pin crystal...</span>
<span class="w">        </span><span class="n">xtal</span><span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span><span class="w">              </span><span class="c1"># Connect the crystal ground pins.</span>
<span class="w">        </span><span class="n">xtal</span><span class="p">[</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">osc1</span><span class="p">,</span><span class="w"> </span><span class="n">osc2</span><span class="w">       </span><span class="c1"># Connect the crystal pins to the oscillator nets.</span>
<span class="w">    </span><span class="k">else</span><span class="p">:</span><span class="w">                              </span><span class="c1"># Otherwise assume it&#39;s a 2-pin crystal...</span>
<span class="w">        </span><span class="n">xtal</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">osc1</span><span class="p">,</span><span class="w"> </span><span class="n">osc2</span><span class="w">        </span><span class="c1"># Using a two-pin crystal.</span>
<span class="w">    </span><span class="n">trim_cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cap</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="w">                  </span><span class="c1"># Instantiate some trimmer caps.</span>
<span class="w">    </span><span class="n">trim_cap</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">osc1</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span><span class="w">     </span><span class="c1"># Connect the trimmer caps to the crystal.</span>
<span class="w">    </span><span class="n">trim_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">osc2</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span>

<span class="c1"># Libraries.</span>
<span class="n">xess_lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="sa">r</span><span class="s1">&#39;C:\xesscorp\KiCad\libraries\xess.lib&#39;</span>
<span class="n">pic32_lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="sa">r</span><span class="s1">&#39;C:\xesscorp\KiCad\libraries\pic32.lib&#39;</span>
<span class="n">pickit3_lib</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="sa">r</span><span class="s1">&#39;C:\xesscorp\KiCad\libraries\pickit3.lib&#39;</span>

<span class="c1"># Global nets.</span>
<span class="n">gnd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Net</span><span class="p">(</span><span class="s1">&#39;GND&#39;</span><span class="p">)</span>
<span class="n">gnd</span><span class="o">.</span><span class="n">drive</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">POWER</span>
<span class="n">vusb</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Net</span><span class="p">(</span><span class="s1">&#39;VUSB&#39;</span><span class="p">)</span>
<span class="n">vusb</span><span class="o">.</span><span class="n">drive</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">POWER</span>
<span class="n">vdd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Net</span><span class="p">(</span><span class="s1">&#39;+3.3V&#39;</span><span class="p">)</span>

<span class="c1"># Some common parts used as templates.</span>
<span class="n">cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;C&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Capacitors_SMD:C_0603&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span>
<span class="n">res</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;R&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Resistors_SMD:R_0603&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">dest</span><span class="o">=</span><span class="n">TEMPLATE</span><span class="p">)</span>

<span class="c1"># Regulate +5V VUSB down to +3.3V for VDD.</span>
<span class="n">vreg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="n">xess_lib</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;TPS793XX&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;TO_SOT_Packages_SMD:SOT-23-5&#39;</span><span class="p">)</span>
<span class="n">noise_cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cap</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;0.01uf&#39;</span><span class="p">)</span>
<span class="n">vreg</span><span class="p">[</span><span class="s1">&#39;IN, EN&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vusb</span>
<span class="n">vreg</span><span class="p">[</span><span class="s1">&#39;GND&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">vreg</span><span class="p">[</span><span class="s1">&#39;OUT&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span>
<span class="n">vreg</span><span class="p">[</span><span class="s1">&#39;NR&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">noise_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
<span class="n">noise_cap</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span>

<span class="c1"># Microcontroller.</span>
<span class="n">pic32</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="n">pic32_lib</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;pic32MX2\*0F\*\*\*B-QFN28&#39;</span><span class="p">,</span>
<span class="w">             </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Housings_DFN_QFN:QFN-28-1EP_6x6mm_Pitch0.65mm&#39;</span><span class="p">)</span>
<span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;VSS&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;VDD&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span><span class="w">  </span><span class="c1"># Main CPU power.</span>
<span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;VUSB3V3&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span><span class="w">  </span><span class="c1"># Power to USB transceiver.</span>
<span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;^VBUS$&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vusb</span><span class="w">  </span><span class="c1"># Monitor power pin of USB connector.</span>
<span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;PAD&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span><span class="w">  </span><span class="c1"># Power pad on bottom attached to ground.</span>

<span class="c1"># Bypass capacitors for microcontroller.</span>
<span class="n">bypass</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cap</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;0.1uf&#39;</span><span class="p">)</span>
<span class="n">bypass</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">bypass</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">bypass</span><span class="p">[</span><span class="mi">2</span><span class="p">][</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;VCAP&#39;</span><span class="p">],</span><span class="w"> </span><span class="n">gnd</span>

<span class="c1"># Microcontroller MCLR circuitry:</span>
<span class="c1">#   Pull-up resistor to VDD.</span>
<span class="c1">#   Filter capacitor to delay exit of reset or eliminate glitches.</span>
<span class="c1">#   Series resistor to isolate capacitor from device programmer.</span>
<span class="n">r_pullup</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;10K&#39;</span><span class="p">)</span>
<span class="n">r_series</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;1K&#39;</span><span class="p">)</span>
<span class="n">filter_cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cap</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;0.1uf&#39;</span><span class="p">)</span>
<span class="n">r_series</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">r_pullup</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;MCLR&#39;</span><span class="p">]</span>
<span class="n">r_pullup</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span>
<span class="n">filter_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">r_series</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span><span class="w"> </span><span class="n">gnd</span>

<span class="c1"># USB connector.</span>
<span class="n">usb_conn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="n">xess_lib</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;USB-MicroB&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;XESS:USB-microB-1&#39;</span><span class="p">)</span>
<span class="n">usb_conn</span><span class="p">[</span><span class="s1">&#39;D\+, D-, VBUS, GND, NC&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;D\+, D-&#39;</span><span class="p">],</span><span class="w"> </span><span class="n">vusb</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span><span class="p">,</span><span class="w"> </span><span class="n">NC</span>
<span class="c1"># Noise filtering/isolation on the USB connector shield.</span>
<span class="n">shld_cap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">cap</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;4.7nf&#39;</span><span class="p">)</span>
<span class="n">shld_res</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;1M&#39;</span><span class="p">)</span>
<span class="n">shld_cap</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">usb_conn</span><span class="p">[</span><span class="s1">&#39;shield&#39;</span><span class="p">]</span>
<span class="n">shld_res</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">usb_conn</span><span class="p">[</span><span class="s1">&#39;shield&#39;</span><span class="p">]</span>
<span class="n">gnd</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">shld_cap</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span><span class="w"> </span><span class="n">shld_res</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>

<span class="c1"># LED with current-limiting resistor driven by microcontroller pin.</span>
<span class="n">led</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s2">&quot;Device&quot;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;led&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Diodes_SMD:D_0603&#39;</span><span class="p">)</span>
<span class="n">led_curr_limit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="s1">&#39;1K&#39;</span><span class="p">)</span>
<span class="n">led_curr_limit</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;RB4&#39;</span><span class="p">],</span><span class="w"> </span><span class="n">led</span><span class="p">[</span><span class="s1">&#39;A&#39;</span><span class="p">]</span>
<span class="n">led</span><span class="p">[</span><span class="s1">&#39;K&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span>

<span class="c1"># Crystal and trim capacitors.</span>
<span class="c1"># crystal = Part(xess_lib, &#39;XTAL4&#39;, footprint=&#39;XESS:32x25-4&#39;, dest=TEMPLATE)</span>
<span class="c1"># osc(pic32[&#39;OSC1&#39;], pic32[&#39;OSC2&#39;], gnd, crystal, cap)</span>
<span class="n">osc</span><span class="p">(</span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC1&#39;</span><span class="p">],</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;OSC2&#39;</span><span class="p">],</span><span class="w"> </span><span class="n">gnd</span><span class="p">)</span><span class="w">  </span><span class="c1"># Use default crystal and trim caps.</span>

<span class="c1"># Port for attachment of device programmer.</span>
<span class="n">prg_hdr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="n">pickit3_lib</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;pickit3_hdr&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Pin_Headers:Pin_Header_Straight_1x06&#39;</span><span class="p">)</span>
<span class="n">prg_hdr</span><span class="o">.</span><span class="n">ref</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;PRG&#39;</span>
<span class="n">prg_hdr</span><span class="p">[</span><span class="s1">&#39;MCLR&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;MCLR&#39;</span><span class="p">]</span>
<span class="n">prg_hdr</span><span class="p">[</span><span class="s1">&#39;VDD&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vdd</span>
<span class="n">prg_hdr</span><span class="p">[</span><span class="s1">&#39;GND&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">prg_hdr</span><span class="p">[</span><span class="s1">&#39;PGC&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;PGEC1&#39;</span><span class="p">]</span>
<span class="n">prg_hdr</span><span class="p">[</span><span class="s1">&#39;PGD&#39;</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;PGED1&#39;</span><span class="p">]</span>

<span class="c1"># Port for attachment of FPGA programming pins.</span>
<span class="n">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Part</span><span class="p">(</span><span class="s1">&#39;conn&#39;</span><span class="p">,</span><span class="w"> </span><span class="s1">&#39;CONN_01x06&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">footprint</span><span class="o">=</span><span class="s1">&#39;Pin_Headers:Pin_Header_Straight_1x06&#39;</span><span class="p">)</span>
<span class="n">port</span><span class="o">.</span><span class="n">ref</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;JTAG&#39;</span>
<span class="n">port</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">vusb</span><span class="p">,</span><span class="w"> </span><span class="n">gnd</span>
<span class="n">port</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;SCK1&#39;</span><span class="p">]</span><span class="w"> </span><span class="c1"># SCK1 output.</span>
<span class="n">port</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;RB5&#39;</span><span class="p">]</span><span class="w">  </span><span class="c1"># PPS: SDI1 input.</span>
<span class="n">port</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;RB15&#39;</span><span class="p">]</span><span class="w"> </span><span class="c1"># PPS: SS1 output.</span>
<span class="n">port</span><span class="p">[</span><span class="mi">6</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">pic32</span><span class="p">[</span><span class="s1">&#39;RA4&#39;</span><span class="p">]</span><span class="w">  </span><span class="c1"># PPS: SDO1 output.</span>

<span class="n">ERC</span><span class="p">()</span>
<span class="n">generate_netlist</span><span class="p">()</span>
</code></pre></div>
		</div> <!--/#entry-content-->
	</div> <!--/#main-->
</div>  <!--/#post-->

		</div>

		<div id="footer">
			<p> </p>
		</div><!-- /#footer -->
	</div><!-- /#container -->
	<div style="display:none"></div>
</body>
</html>